home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #1 / Amiga Plus 1995 #1.iso / fish-disketten / fish_921-930 / d928 / addtools / addtoolsdoc-e < prev    next >
Text File  |  1994-12-13  |  15KB  |  334 lines
  1. $VER: AddTools.doc 1.11 (10.8.93) © Alessandro Sala
  2.  
  3.                     AddTools version 1.11 10-Aug-1993
  4.                    Copyright © 1993 By Alessandro Sala
  5.  
  6.              Requires AmigaOS v2.04 ( Kickstart v37 ) or later
  7.  
  8.  
  9.                                ------------
  10.                                 Disclaimer
  11.                                ------------
  12.  
  13.    This program is provided "as is" without warranty of any kind, either
  14. expressed or implied, including, but not limited to, the implied warranty
  15. of fitness for a particular purpose.  Though every care has been taken to
  16. make this program system-friendly and bugs-free, the entire risk as to the
  17. results, reliability and performance of this program is assumed by you.
  18.  
  19.  
  20.                             ------------------
  21.                              Copyright notice
  22.                             ------------------
  23.  
  24.    This program is "FreeWare": it can be freely copied and distributed for
  25. non-commercial purposes, provided that no file is added to or removed from the
  26. distribution archive and no charge, beside a nominal media cost, is requested.
  27.    Nevertheless the program remains COPYRIGHT of the Author: you cannot
  28. patch, reverse engineer or otherwise modify the program, the documentation and
  29. every other file found in the distribution archive.
  30.    Compressing in executable form is only allowed for personal use, not
  31. when the program is being distributed: LHARC'ing in an archival form is
  32. explicitly allowed for distribution convenience.
  33.    Furthermore you cannot embed the program in any other software without
  34. the written permission of the author.
  35.  
  36.                      ------------------------------------
  37.                      Contents of the distribution archive
  38.                      ------------------------------------
  39.  
  40.     AddTools                 : The main program
  41.     AddToolsData             : Configuration file example
  42.     AddToolsDoc-E            : English documentation
  43.     Catalogs                 : Drawer
  44.       AddTools.ct            : Empty translation file
  45.       italiano               : Drawer
  46.         AddTools.catalog     : Italian language support file
  47.     MTCopy                   : Example of AmigaDos script for use with AddTools
  48.  
  49.     AddTools.info           \
  50.     AddToolsData.info        |
  51.     AddToolsDoc-E.info       |       : Related icons
  52.     Catalogs.info            |
  53.       AddTools.ct.info       |
  54.     MTCopy.info             /
  55.  
  56.  
  57.                              1. Introduction
  58.                              ---------------
  59.  
  60.    AddTools is a very simple utility, written mainly to experiment with the
  61. new applications menu ( "Tools" ) of AmigaOS release 2, but I found it very
  62. useful so I decided to release it as Freeware with the hope that someone
  63. else will find it convenient.
  64.    The program allows you to add your own items to the "Tools" menu of
  65. AmigaOS_2.04's Workbench Screen. Unlike other menu utilities, which only add
  66. the ability to run programs by menu, AddTools can also pass them some
  67. parameters on "the fly" in the form of icons ( from now on called " icon
  68. parameters" ), selected before choosing the desired menu item. You can also
  69. provide default values if no icons are selected, and you can decide if the
  70. the program must be run in either synchronous or asynchronous mode when
  71. multiple icon parameters are selected.
  72.  
  73.                          --------------------------
  74.                          Changes since version 1.00
  75.                          --------------------------
  76.  
  77.    If you already know AddTools, here are some major differences from the
  78. previous version:
  79.  
  80.   --  The limit of 10 menu items has been removed.
  81.  
  82.   --  Using synchronous items no longer locks AddTools until all parameters have
  83. been processed. Now there is an independent task handling synchronous items.
  84.  
  85.  
  86.   --  Now supports localization if you have OS 2.1 or later; currently
  87. supported languages are:
  88.                          English (built-in)
  89.                          Italian
  90.  
  91.       To use a language different from english you need the 'AddTools.catalog'
  92. file for that language in your 'SYS:Locale/catalogs/<language>/' directory
  93. or in 'catalogs/<language>/' inside AddTools directory.
  94.  
  95.  
  96.   --  If you choose an item with less than 2 icons selected ( that is 1 or
  97. none ) it will now run in asynchronous mode regardless of the sync/async
  98. flag.
  99.  
  100.  
  101.   --  There is now a new menu item, named 'AddTools...', which is
  102. automatically added at the end of user items. Selecting 'AddTools...' you
  103. will see a requester asking you if you want to quit the program.
  104.  
  105.  
  106.   --  Fixed a bug in icon parameters handling code: if an item had default
  107. parameters inside the '[]', the command line after the ']' was ignored: now
  108. it's ok.
  109.  
  110.  
  111.   --  Now supports multiple '[<default_params>]' strings in a single command
  112. line.
  113.  
  114.  
  115.                                 ------------
  116.                                 Installation
  117.                                 ------------
  118.  
  119.    To install AddTools you can simply copy it in some drawer, typically
  120. your SYS:WBStartup drawer. Then create the configuration file AddToolsData, as
  121. explained below, and put it in your S: volume ( normally the SYS:S drawer ) or
  122. in the same directory as AddTools. If you have OS 2.1 or later and you want to
  123. take advantage of the localization, you must also copy the 'catalogs' drawer,
  124. found in the AddTools distribution archive, into the same drawer as AddTools,
  125. or you can copy the 'AddTools.catalog' file ( found in the 'catalogs/<language>/'
  126. drawer ) into your 'LOCALE:catalogs/<language>/' drawer.
  127.    If your language is not currently available, you can fill in the empty
  128. translation file found in the catalogs drawer ( catalogs/AddTools.ct ) and
  129. send it to me by E-Mail ( the address is at the end of this file ). I will
  130. create a new '<your-language>/AddTools.catalog' file and E-Mail it to you as
  131. soon as possible, and the next version of AddTools will support one more
  132. language !
  133.  
  134.  
  135.                          2. Configuration and usage
  136.                          --------------------------
  137.  
  138.  
  139. -2.1- The configuration file
  140.  
  141.    AddTools can be started from workbench by double-clicking its icon or by
  142. placing it in your WBStartup drawer to have it activated every time you
  143. boot; in this case remember to add the "DONOTWAIT" ToolType.
  144.    You can also run AddTools from a CLI or from your user-startup; in this
  145. case use the RUN command to start AddTools in the background.
  146.    When AddTools is started, it looks in the current directory to see if a
  147. configuration file named "AddToolsData" exists: if not, it then searches
  148. in the S: volume (typically your SYS:S drawer) and aborts if it doesn't find
  149. there the configuration file.
  150.    The "AddToolsData" file contains the description of the various menu items
  151. you want to add to the Tools menu. Every item is defined by three lines with
  152. the following format:
  153.  
  154.       <Line 1>    Menu_item_text
  155.       <Line 2>    Menu_item_associated_command_line_with_parameters
  156.       <Line 3>    Synchronous/Asynchronous_mode_flag
  157.  
  158. these three lines are repeated for every menu item you want to add. Here
  159. comes an explanation of every line:
  160.  
  161.    Line 1 : Menu item text :   This is the text you want to be displayed in
  162.                              the tools menu: note that shortcuts are not
  163.                              available at the moment.
  164.  
  165.  
  166.    Line 2 : Command line   :   This will normally be the complete path and
  167.                              name of the program you want to be run when
  168.                              choosing this menu item, possibly followed by
  169.                              parameters. If you want to pass this program
  170.                              possible icons as parameters you must include
  171.                              a special char sequence in the command line, as
  172.                              explained below.
  173.  
  174.  
  175.    Line 3 : Sync/Async     :   This will be either an "A" or an "S" char to
  176.                              indicate A)synchronous or S)ynchronous execution
  177.                              mode (see below).
  178.  
  179.    In the distribution archive you can find an example of the 'AddToolsData'
  180. configuration file.
  181.  
  182. -2.2- Synchronous vs. Asynchronous mode
  183.  
  184.    If, in the third line of a menu item definition, you specified
  185. asynchronous mode, AddTools will execute the associated command line
  186. asynchronously ( as you might expect ! ), that is not waiting for the
  187. completion of the program execution. This is the best way if the program has
  188. fixed parameters, directly passed in by the command line you provided. This
  189. mode can also be useful with icons parameters, but I will explain this later.
  190.    On the other hand, in synchronous mode, if you select more than one icon
  191. parameter, AddTools will wait until the program execution has completed before
  192. handling successive icon parameters. The usefulness of this mode will come
  193. clear in the next section when I' ll discuss of multiple icon parameters.
  194.  
  195.  
  196. -2.3- Icon parameters
  197.  
  198.    If, before choosing menu item, you select one or more icons, the
  199. menu item associated program will be able to see them as if they were
  200. command line parameters. To enable this feature for a particular item, you
  201. must specify in the item's command line a string with the following format:
  202.  
  203.       [<default_params>]
  204.  
  205. where '<default_params>' is whatever string you want and '[' and']' are
  206. simply what they seem: open and closed square brackets !
  207.  
  208.  
  209. -2.3.1- Single icon parameter
  210.  
  211.    When an icon parameter is selected, its complete volume:path/name string
  212. will be substituted to the <default_params> string, and the two square
  213. brackets will be removed. The resulting command line is then executed.
  214.    If no icon is selected when the menu item is chosen, no substitution will
  215. occur and the square brackets will be removed, so the resulting command line
  216. will contain the <default_params> string which will act as a default parameter
  217. block. Note that the [xxx] can be put everywhere in the command line, even
  218. mixed with other parameters which will be preserved after substitution.
  219.  
  220.       Example: C:Ed [temp] WIDTH=64
  221.  
  222.    this line will execute the editor Ed with a 64 columns wide display and a
  223. 'temp' filename if no icon is selected, otherwise the selected icon will
  224. be edited.
  225.    Note that you can also set <default_params> to a null string, i.e. '[]',
  226. and in this case no default values will be passed if you don't select
  227. an icon ( similar to the AmigaDOS command 'alias' ).
  228.  
  229.  
  230. -2.3.2- Multiple icon parameters
  231.  
  232.    If more than one icon is selected when the menu item is activated, all
  233. the icons will be passed in as parameters in the following way: the first
  234. icon's volume:path/name gets substituted and the command line is executed; if
  235. the execution mode is synchronous AddTools waits for the program execution
  236. to complete, then it substitutes the second icon, executes the resulting
  237. command line and so on until all icons are processed. If asynchronous mode is
  238. set, AddTools will immediately continue substituting icons and executing
  239. command lines: this way you will get every icon concurrently processed by
  240. its own copy of the program associated with the menu item.
  241.    From version 1.10 you can specify more than one [<default_params>] string
  242. in the command line. In this way the first icon you selected will be substituted
  243. in place of the first parameter, the second icon in place of the second parameter
  244. and so on. If the number of icons selected is greater than the number of
  245. parameters, this process is repeated - immediatly if synchronous mode is set,
  246. when the program returns, otherwise - on a new copy of the command line, until
  247. all icons are processed.
  248.  
  249.                            3. Terminating AddTools
  250.                            -----------------------
  251.  
  252. You can execute as many copies of AddTools as you want, but to remove one or
  253. more of them ( and the associated menu items ) from the memory you can
  254. select the appropriate 'AddTools ...' menu item and answer 'Yes' to the
  255. subsequent requester. If you launched AddTools from Workbench or through the
  256. WBStartup drawer, you can also terminate AddTools by sending a BREAK signal
  257. ( CTRL-C ) through a task utility ( such as TaskX by Steve Tibbett ). If, on
  258. the other hand, AddTools was run from a CLI you can use the following procedure:
  259.  
  260.    1) Open a CLI
  261.    2) Issue the 'STATUS' command and note the process number of AddTools
  262.    3) Issue 'BREAK <n> C' where <n> is the process number noted above
  263.  
  264.  
  265.                          4. Criticism and suggestions
  266.                          ----------------------------
  267.  
  268.    I hope you will find AddTools useful, and if you have any criticism,
  269. suggestions, bug report, ideas for enhancements in possible future versions,
  270. you can write ( in Italian or English ) at the following address:
  271.  
  272.         Alessandro Sala
  273.         Via A. Grandi, 16
  274.         20014 Nerviano (MI)
  275.         Italy
  276.  
  277.     If you have E-Mail capability you can also contact me at the following
  278. Internet address (at least until the end of January 1994):
  279.  
  280.         tser1506@cdc835.cdc.polimi.it
  281.  
  282.    And PLEASE respect my privacy and DO NOT try to contact me by phone.
  283.  
  284.                                                   Thank you
  285.  
  286. **********************************************************************************
  287.                                     History
  288. **********************************************************************************
  289.  
  290. ------------
  291. Version 1.11
  292. ------------
  293.  
  294.   --  Corrected various mistakes in English inside this file ( further
  295. corrections in the next version !!! ).
  296.  
  297.   --  In version 1.00 there was a limit of 10 menu items: now it has been
  298. removed.
  299.  
  300.   --  Using synchronous items no longer locks AddTools until all parameters have
  301. been processed. Now there is an independent task handling synchronous items.
  302.  
  303.   --  Now supports localization if you have OS 2.1 or later; currently
  304. supported languages are:
  305.                          English (built-in)
  306.                          Italian
  307.  
  308.   --  If you choose an item with less than 2 icons selected ( that is 1 or
  309. none ) it will now run in asynchronous mode regardless of the sync/async
  310. flag.
  311.  
  312.   --  New menu item, named 'AddTools...', automatically added at the end of user
  313. items to allow simpler termination of AddTools.
  314.  
  315.   --  Fixed a bug in icon parameters handling code: if an item had default
  316. parameters inside the '[]', the command line after the ']' was ignored.
  317.  
  318.   --  Added support for multiple '[<default_params>]' strings in a single
  319. command line.
  320.  
  321.  
  322. ------------
  323. Version 1.10
  324. ------------
  325.  
  326.      Internal beta version ( never released ).
  327.  
  328.  
  329. ------------
  330. Version 1.00
  331. ------------
  332.  
  333.      First release!
  334.